Skip to main content

Caching Overview

This document describes the caching strategy in ValkyrAI backend for performance and safety.

Goals

  • Reduce repeated ACL and SID lookups on hot paths.
  • Keep permission decisions fresh with micro‑TTL caching.
  • Avoid distributed state until measured; enable upgrade path to Redis later.

What’s Implemented

  • Ehcache 3 (JCache) as in‑process cache provider.
  • Spring Cache wired via JCacheCacheManager in valkyrai/src/main/java/com/valkyrlabs/valkyrai/config/CachingConfig.java:1.
  • Caches and TTLs:
    • sidByUsername: 30m TTL, caches AclSid by username/authority.
    • permissionDecisions: 15s TTL, caches AclService.hasPermission(...) results.
    • Existing caches kept: aclCache, entityCache, entityListCache, entityPageCache.

Hot Path Details

  • AclSidLookupService.findFirstBySid(String): annotated with @Cacheable("sidByUsername"), used by AclService for SID ID resolution and anonymous lookups.
  • AclService.hasPermission(ObjectIdentity, String, Permission): annotated with @Cacheable("permissionDecisions") and evicted on write operations that could affect permissions.

Eviction

  • createAcl, updateAcl, grantPermission, revokePermission now evict permissionDecisions (and aclCache where appropriate) to prevent stale authorization.

Logging

  • KMSSecureFieldAspect logging level set to WARN in application.yaml to reduce noise in production.

Future: Distributed Caching

  • If/when needed, introduce Redis for coarse‑grained caches (e.g., read‑only lists), keeping permission decisions local. Minimal code changes required since Spring Cache abstractions are used.